Introduction to the Crescent Internet ToolPak

Thank you for purchasing the Crescent Internet ToolPak. It is a comprehensive collection of controls that provide Visual Basic programmers with a powerful and efficient tool for building applications and utilities for use with both the Intranet and the Internet.

From this topic, you can access the following information about the Crescent Internet ToolPak:

•	The Crescent Internet ToolPak product components

•	The Crescent Internet ToolPak Architecture

•	File distribution and application deployment

•	Hardware and software requirements

•	Technical Support

For programmers new to the Internet or the Internet application development environment, we recommend that you read through the glossary to familiarize yourself with the terminology.


The Crescent Internet ToolPak Components
Introduction Topics

The Crescent Internet ToolPak consists of a collection of Visual Basic controls, an Internet Mail Wizard, and a comprehensive set of demonstration programs.


The Crescent Internet ToolPak Controls
Introduction Topics

This product contains the following controls:

Name	Control File	Description
FTP Control (CIFTP)	CIFTP.OCX CIFTP16.OCX	Enables the programmer to build client applications that support file transfers to and from FTP servers.
WEB Control  (CIHTTP)	CIHTTP.OCX CIHTTP16.OCX	Enables the programmer  to build applications that access HTTP servers.
IMAP4 Component(CIIMAP4)	CIIMAP4.OCX	Enables the programmer  to build applications that access IMAP4 servers.
Retrieve Mail Control (CIPOP)	CIMAIL.OCX CIMAIL16.OCX	Enables the programmer to build client applications that can retrieve mail from POP3 mail servers.
MIME Control  (CIMIME)	CIMIME.OCX	Enables the programmer to build client applications that encode files that you intend to mail, or decode files that have been encoded using the MIME standard.
NEWS Control (CINEWS)	CINEWS.OCX CINEWS16.OCX	Enables the programmer to build client applications that can retrieve or post articles from or to NNTP servers.
RAS Control (CIRAS)	CIRAS.OCX CIRAS16.OCX	Enables the programmer to build client applications that can provide programmatic dial-up access to a network via SLIP, PPP, or the RAS proprietary protocol.
Client/Server Control (CITCP)	CITCP.OCX CITCP16.OCX	Enables the programmer to build both client and server applications that support general purpose TCP/IP messaging and file transfer.
TCP/IP Server Control (CIServer)	CISERVER.OCX	Enables the programmer to build customized server applications.
UUEncode/Decode Control (CIUU)	CIUU.OCX	Enables the programmer to build client applications that can encode files that you intend to mail, and decode files that have been encoded using the UUEncode/Decode standard.


The Internet Mail Wizard
Introduction Topics

The Internet Mail Wizard provides a convenient way to build simple applications with the Mail control.

Simply complete the text boxes displayed on the form as prompted by the wizard. Once you've answered the questions, the wizard builds a working application and ends itself. You can use the applications as built by the wizard, or as a stepping stone to building more complex applications. By default, they are installed in the CITPAK/WIZARD directory.

You access the Internet ToolPak Wizard from the Add-In Menu.

NOTE  	The Internet Mail Wizard is supported only in a 32-bit and Visual Basic 4.0 environment.


The Demonstration Programs
Introduction Topics

The demonstration programs illustrate some programming uses for the controls. By default, they are installed in the CITPAK/DEMOS directory. See the  Demonstration ReadMe file for the list of demonstration files.


The Crescent Internet ToolPak Architecture
Introduction Topics

The Crescent Internet ToolPak controls enable you to develop client applications for Internet servers that include HTTP, NNTP, FTP, SMTP, TCP/IP and POP3 servers. (Note the TCP/IP control also enables you to create server applications.)

The client application creates requests for data from the server. The server responds to the request by returning data to the control, or by returning no data to the control to indicate that the request failed.

Each of the Internet ToolPak controls support a unique set of methods that, when called, construct a request that complies with the server's requirements. (The server's requirements depend on the protocol or service that the server is providing.) The control constructs the request by taking the data from the properties. Once the request is constructed and sent to the server, the method is complete, and control returns to the application which can call another method and send another request to the server. When the client application receives a response from the server, the control internally parses the data, updates the appropriate properties and fires an event to indicate that the server's response was received. This is known as asynchronous programming.

If the application built and sent the request to the server, then waited for the server to respond by polling for the response, it would be called polled or synchronous programming. The application would be blocked, or suspended, until the server responded. In the asynchronous model, you simply send a request, and when the data is received from the server, the control fires an event to indicate that the data was received. You must place code in the event to process the data as it is received.

The advantage of the asynchronous structure is that your application continues with other tasks as it waits for data from the server. Once the server returns the data to the control, the application immediately responds to it, thus increasing performance. However, as the programmer, you must be aware that the properties that are updated with data from the server may not be available immediately after calling a method. Instead, you must place code that checks property values in the appropriate event module.

The following code sample illustrates the asynchronous architecture, with code that connects a client application to an HTTP server. With most of the Internet ToolPak controls, you must set the HostName (or HostAddress) property and the port property to the port number on the server that provides the desired service (in this case the HTTP Port).

The code in the Form_Load procedure looks like this:

Sub Form_Load()
CIHTTP1.HostName = "www.myhost.com"
CIHTTP1.HTTPPort = 80
Result = CIHTTP.ConnectToHTTPServer

Sub CIHTTP1_HTTPServerConnection()
'Code to perform once the connection attempt succeeds.

Sub CIHTTP1_WSAError(ByVal error_number As Integer)
'Code to perform if the connection attempt fails.

The application is connected when the HTTPServerConnection event fires. When the connection attempt succeeds, Result is an integer that represents the socket number opened by the ConnectToHTTPServer method. When the connection attempt fails, Result is 0 and the WSAError event fires. Note that the WSAError event occurs as a result of a WinSock error, and not an error from the server.

All of the controls adhere to the asynchronous programming model except the CIMAIL controls which adhere to the polled programming model (CIPOP and CISMTP).


About Server Connections
Introduction Topics

To identify computers on the network, TCP/IP, the Internet protocol, requires that each computer has a unique address known as a host address. A host address looks like this:

198.137.64.1

The Crescent Internet ToolPak controls implement this value as the HostAddress property.

Because a host address can be difficult to remember there is an alternate addressing system called the Domain Name System (DNS). The DNS uses a host name to identify the computer on the Internet. A host name looks like this:

organizationname.com

A host name has two parts: an organization name followed by the domain in which the host resides. In this example, the organization name is organizationname, and the domain is .com. A domain generally identifies the type of organization to which a host belongs. The following table shows some examples of Internet domains.

This domain . . .	Identifies this type of organization . . .
.com	Identifies commercial organizations.
.org	Identifies non-profit organizations.
.gov	Identifies U.S. government organizations.
.edu	Identifies educational institutions.
The Crescent Internet ToolPak controls implement the host name address as the HostName property.

Another advantage in using the DNS name rather than the Internet address is that host names generally do not change, though the IP address can. For example, if Progress Software, Inc. moved from Massachusetts to Texas, its IP address probably would change, while the DNS name (progress.com) probably would not. As a result, applications that access a machine by its host name would be unaffected while applications that access a machine by address would be.


Selecting the Control
Introduction Topics

After you install the Crescent Internet ToolPak, you must select the control in Visual Basic and write Visual Basic code. If you are using Visual Basic 4.0, follow these steps from the Project design screen to select the control:

1.	If you are using Visual Basic 4.0, select Tools→Custom Controls; if you are using Visual Basic 5.0, select Project→Components.

2.	Select the Controls folder.

3.	In the Controls Dialog Box, select the appropriate CITP 4.0 control.

4.	Select OK.


Writing the Code
Introduction Topics

Generally, you must declare the variables you will use, set the appropriate property values, and use the appropriate CITP 4.0 methods and events. For precise steps, refer to the specific control descriptions. For additional examples of how to use the methods and events, refer to the control demos provided with the CITP 4.0 software.


Error Handling
Introduction Topics

There are three types of errors that you might encounter with the Internet ToolPak controls They are:

•	WinSock Errors

•	WinSock errors can occur for many reasons which include, but are not limited to, an unreachable network, a network time-out error, or an invalid host.

•	WinSock errors cause the WSAError event to fire. They also return a non-zero value to the called method.

•	For more information about WinSock errors, see the Microsoft Web page at http://www.sockets.com or see the Windows Sockets Network Programming book.

NOTE  	WinSock errors do not apply to the 32-bit CIFTP control which uses the WinInet API.

•	WinInet Errors. The 32-bit CIFTP control uses the WININET.DLL for high-level methods instead of the WinSock API. WinInet errors cause the InternetError event to fire.

•	Server Errors. A server error can occur when the server is not able to execute your command. This might occur because the data that you are requesting does not exist, or you don't have authority to perform the action. The server return codes are returned to the PacketReceived event.

The CITPAK.BAS file contains WinSock and WinInet error codes as well as server return codes.


Standards Compliance
Introduction Topics

The Internet ToolPak controls comply, where practical, with the current Internet standards for the protocol that they support. The Internet standards are defined in documents called Request For Comments (RFC) documents. The following table identifies the protocol, the associated Internet ToolPak control and the RFC that it complies with.

This Protocol	and this control	comply with this RFC
SMTP	CISMTP	821
POP	CIPOP	1725
FTP	CIFTP	959
HTTP	CIHTTP	None
MIME	CIMIME	1521 and 1522
NNTP	CINEWS	977
RAS	CIRAS	None
TCP/IP	CITCP	None
UUEncode	CIUU	None
The CITelnet form (CITelnet)

The CITelnet form complies with the Telnet standard defined in RFC 854.


File Distribution and Application Deployment
Introduction Topics

You can distribute any application you create using Internet ToolPak routines, as long as you distribute the application only as an executable. You may also distribute the Internet ToolPak control libraries (.OCX).

See the "End-user License Agreement" at the beginning of the Crescent Internet ToolPak User's Guide for more information about the license to use the Crescent Internet ToolPak.

The deployment platforms, which run applications containing Internet ToolPak controls, must have the same software installed as the development platform, as well as the same versions of Microsoft TCP/IP, WinSock, and service packs for their respective operating system.

The following table lists dynamic link libraries that must be distributed with applications that use Internet ToolPak controls. See the README.htm file for more information.

Control	For 16-Bit Applications	For 32-Bit Applications
CIFTP control	OC25.DLL *	MFC42.DLL * MSVCRT.DLL MSVCIRT.DLL OLEPRO32.DLL * WININET.DLL **
PDQCOMM control, and PDQTAPI (32 bit only)	OC25.DLL *	MFC40.DLL * MSVCRT40.DLL OLEPRO32.DLL *
CIRAS control	OC25.DLL*	MFC42.DLL * MSVCRT.DLL MSVCIRT.DLL OLEPRO32.DLL * RNAPH.DLL ***
All other controls	OC25.DLL*	MFC42.DLL * MSVCRT.DLL MSVCIRT.DLL OLEPRO32.DLL *
* These DLLs must be registered.
** The wininet.dll is required only when your application employs the CIFTP high-level methods PutFile, GetFile, and/or GetDirectory. This dll has special installation requirements. Please see the Microsoft Knowledge Base Article Q185375 for information on installing this dll properly. This document can be downloaded from www.microsoft.com.
 *** The RNAPH.DLL is required only when deploying an application that uses the 32-bit CIRAS control on Windows 95.


System Requirements
Introduction Topics

To run the Internet ToolPak, you must have the following:

•	One of the following operating systems

•	Microsoft Windows for Workgroups 3.11 and Microsoft TCP/IP stack

•	Microsoft Windows NT 4.0 (commercial release only) with Service Pack 3, Microsoft TCP/IP stack, and Remote Access Service (RAS)

•	Microsoft Windows 95 with Kernel Update (krnlupd.exe) and Service Pack 1 or OSR2, Remote Access Service (RAS), and TCP/IP

•	Microsoft Windows 98

•	Microsoft Visual Basic 4.0, Microsoft Visual Basic 5.0 with Service Pack 3, or Microsoft Visual Basic 6.0 and the hardware and software that they require to function.

•	Microsoft Internet Explorer 4.0 or greater.

NOTE  See the README.htm file for additional information on any Microsoft service packs and product updates that also are required.


Crescent Internet ToolPak Technical Support
Introduction Topics

The Crescent technical support staff is ready to help you with problems that you encounter when installing or using Internet ToolPak. It does not matter what component of Internet ToolPak is causing problems; the Crescent technical support staff will do its best to help you succeed with Internet ToolPak.

If you need technical support, contact us using any of the following methods:

By Telephone	You can contact Crescent's North American Premium Support staff Monday through Friday from 9:00 a.m. to 12:00 p.m., and from 12:30 p.m. to 5:00 p.m. EST. Please see the README.htm file that is included in the Crescent Internet ToolPak software for detailed information.
By Internet	Contact Crescent using the Internet address crescent-support@progress.com.
By Mail	Address your correspondence to: Technical Support Crescent Division, Progress Software Corporation 14 Oak Park Bedford, MA 01730 United States
Via WWW site	Contact Crescent using the URL http://crescent.progress.com
Please have your product name, version number, serial number, and system configuration information available so that the Crescent technical support staff can process your support requests as efficiently as possible.

To maximize the effectiveness of your contact with Crescent's technical support, please have pertinent information available regarding your problem when you call. Before you call for technical support:

1.	Please read through the documentation thoroughly.

2.	Check the Demo programs.

3.	Check the Frequently Asked Questions topic under Technical Support on the Crescent Web Page.

We have found that many problems can be solved by applying the information contained in the documentation. If, after reading through text, you still cannot resolve your problem, please perform the following:

GPF? If you are getting a GPF (General Protection Fault), write down the information that is displayed when the error occurs. Also, note what your code was doing (in general terms).

ISOLATE IT. Try to isolate the cause of the error. If possible, step through your code with F8 and F9. Try to find the one line of code that is causing the error.

SCALE IT DOWN. Try to reproduce the problem in a small test program that you can send in. Call the technical support line to discuss your question and possibly arrange the method by which you can send in your test code.

CALL CRESCENT.